Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

SoundView

Inherits From:	View : Responder : Object

Declared In:	soundkit/SoundView.h

Class Description

A SoundView object provides a graphical representation of sound data.  This data is taken from an associated Sound object.  In addition to displaying a Sound object's data, a SoundView provides methods that let you play and record into the Sound object, and peform simple cut, copy, and paste editing of its data.  A cursor into the display is provided, allowing the user to set the insertion point and to create a selection over the sound data.  

Sound Display

Sounds are displayed on a two-dimensional graph.  The amplitudes of individual samples are measured vertically and plotted against time, which proceeds left to right along the horizontal axis.  A SoundView's coordinate system is scaled and translated (vertically) so full amplitude fits within the bounds rectangle with 0.0 amplitude running through the center of the view.

For many sounds, the length of the sound data in samples is greater than the horizontal measure of the bounds rectangle.  A SoundView employs a reduction factor to determine the ratio of samples to display units and plots the minimum and maximum amplitude values of the samples within that ratio.  For example, a reduction factor of 10.0 means that the minimum and maximum values among the first ten samples are plotted in the first display unit, the minimum and maximum values of the next ten samples are displayed in the second display unit and so on.

Lines are drawn between the chosen values to yield a continuous shape.  Two drawing modes are provided:

·	In NX_SOUNDVIEW_WAVE mode, the drawing is rendered in an oscilloscopic fashion.

·	In NX_SOUNDVIEW_MINMAX mode, two lines are drawn, one to connect the maximum values, and one to connect the minimum values.

As you zoom in (as the reduction factor decreases), the two drawing modes become indistinguishable.

Autoscaling the Display

When a SoundView's sound data changes (due to editing or recording), the manner in which the SoundView is redisplayed depends on its autoscale flag.  With autoscaling disabled, the SoundView's frame grows or shrinks (horizontally) to fit the new sound data and the reduction factor is unchanged.  If autoscaling is enabled, the reduction factor is automatically recomputed to maintain a constant frame size.  By default, autoscaling is disabled; this is to accommodate the use of a SoundView object as the document of a ScrollView.

Instance Variables

id sound;

id reduction;

id delegate;

NXRect selectionRect;

int displayMode;

float backgroundGray;

float foregroundGray;

float reductionFactor;

struct {
	unsigned int  disabled:1;
	unsigned int  continuous:1;
	unsigned int  calcDrawInfo:1;
	unsigned int  selectionDirty:1;
	unsigned int  autoscale:1;
	unsigned int  bezeled:1;
 	unsigned int notEditable:1;
    	 unsigned int notOptimizedForSpeed:1;
} svFlags;

sound 	The object's Sound.

reduction 	The data reduced version of the object's Sound.

delegate 	The object's delegate.

selectionRect 	The object's current selection.

displayMode 	Display mode; NX_SOUNDVIEW_MINMAX by default.

backgroundGray 	Background color; NX_WHITE by default.

foregroundGray 	Foreground color; NX_BLACK by default.

reductionFactor 	The ratio of sound samples to display units.

svFlags.disabled 	Does the object (not) respond to mouse events?

svFlags.continuous 	Does the object respond to mouse dragged events?

svFlags.calcDrawInfo 	Does drawing info need to be recalculated?

svFlags.selectionDirty 	Has the object changed (but not been played)?

svFlags.autoscale 	Does it rescale the display when the sound data changes?

svFlags.bezeled 	Does the object have a bezeled border?

svFlags.notEditable 	Is the sound data not editable?

svFlags.notOptimizedForSpeed	Is the object not optimized for fast loading?

Method Types

Initializing a SoundView object 	- initFrame:

Freeing a SoundView instance	- free

Modifying the object	- scaleToFit
- setBackgroundGray:
- setBezeled:
- setContinuous:
- setDelegate:
- setDisplayMode:
- setEnabled:
- setForegroundGray:
- setOptimizedForSpeed:
- setSound:
- sizeToFit

Querying the object	- backgroundGray
- delegate
- displayMode
- foregroundGray
- getSelection:size:
- isAutoScale
- isBezeled
- isContinuous
- isEnabled
- isOptimizedForSpeed
- reductionFactor
- sound

Selecting and editing the sound data
- copy:
- cut:
- delete:
- mouseDown:
- paste:
- selectAll:
- setSelection:size:
- isEditable
- setEditable:

Pasteboard and Services support	- pasteboard:provideData:
- readSelectionFromPasteboard:
- validRequestorForSendType:andReturnType:
- writeSelectionToPasteboard:types:

Modifying the display coordinates
- setAutoscale:
- setReductionFactor:

Drawing the object	- drawSelf::
- drawSamplesFrom:to:
- hideCursor
- showCursor
- sizeTo::

Responding to events	- acceptsFirstResponder
- becomeFirstResponder
- resignFirstResponder

Performing the sound data	- pause:
- isPlayable
- play:
- record:
- resume:
- soundBeingProcessed
- stop:

Archiving the object	- read:
- write:

Accessing the delegate	- didPlay:
- didRecord:
- hadError:
- tellDelegate:
- willPlay:
- willRecord:

Instance Methods

acceptsFirstResponder

- (BOOL)acceptsFirstResponder

If the SoundView is enabled, this returns YES, allowing the SoundView to become the first responder.  Otherwise, it returns NO.  This method is automatically invoked by objects defined by the Application Kit; you should never need to invoke it directly.

backgroundGray

- (float)backgroundGray

Returns the SoundView's background gray value (NX_WHITE by default).

becomeFirstResponder

- becomeFirstResponder

Promotes the SoundView to first responder.  You never invoke this method directly.  Returns self.

copy:

- copy:sender

Copies the current selection to the pasteboard.  Returns self.

cut:

- cut:sender

Deletes the current selection from the SoundView, copies it to the pasteboard, and sends a soundDidChange: message to the delegate.  The insertion point is positioned to where the selection used to start.  Returns self.

delegate

- delegate

Returns the SoundView's delegate object.

delete:

- delete:sender

Deletes the current selection from the SoundView's Sound and sends the soundDidChange: message to the delegate.  The deletion isn't placed on the pasteboard.  Returns self.

didPlay:

- didPlay:sender

Used to redirect delegate messages from the SoundView's Sound object; you never invoke this method directly.

didRecord:

- didRecord:sender

Used to redirect delegate messages from the SoundView's Sound object; you never invoke this method directly.

displayMode

- (int)displayMode

Returns the SoundView's display mode, one of NX_SOUNDVIEW_WAVE (oscilloscopic display) or NX_SOUNDVIEW_MINMAX (minimum/maximum display; this is the default).

drawSamplesFrom:to:

- drawSamplesFrom:(int)first to:(int)last

Redisplays the given range of samples.  Return self.

drawSelf::

- drawSelf:(const NXRect *)rects :(int)rectCount

Displays the SoundView's sound data.  The selection is highlighted and the cursor is drawn (if it isn't currently hidden).  Returns self.

You never send the drawSelf:: message directly to a SoundView object.  To cause a SoundView to draw itself, send it one of the display messages defined by the View class.

foregroundGray

- (float)foregroundGray

Returns the SoundView's foreground gray value (NX_BLACK by default).

free

- free

Frees the SoundView but not its Sound object nor its delegate.  The willFree: message is sent to the delegate.

getSelection:size:

- getSelection:(int *)firstSample size:(int *)sampleCount

Returns the selection by reference.  The index of the selection's first sample (counting from 0) is returned in firstSample.  The size of the selection in samples is returned in sampleCount.  The method itself returns self.

hadError:

- hadError:sender

Used to redirect delegate messages from the SoundView's Sound object; you never invoke this method directly.

hideCursor

- hideCursor

Hides the SoundView's cursor.  This is usually handled automatically.  Returns self.

initFrame:

- initFrame:(const NXRect *)frameRect

Initializes the SoundView, fitting the object within the rectangle pointing to by frameRect.  The initialized SoundView doesn't contain any sound data.   Returns self.

isAutoScale

- (BOOL)isAutoScale

Returns YES if the SoundView is in autoscaling mode, otherwise returns NO.

isBezeled

- (BOOL)isBezeled

Returns YES if the SoundView has a bezeled border, otherwise returns NO (the default).

isContinuous

- (BOOL)isContinuous

Returns YES if the SoundView responds to mouse-dragged events (as set through setContinuous:).  The default is NO.

isEditable

- (BOOL)isEditable

Returns YES if the SoundView's sound data can be edited.

isEnabled

- (BOOL)isEnabled

Returns YES if the SoundView is enabled, otherwise returns NO.  The mouse has no effect in a disabled SoundView.  By default, a SoundView is enabled.

isOptimizedForSpeed

- (BOOL)isOptimizedForSpeed

Returns YES if the SoundView is optimized for speedy display.  SoundViews are optimized by default.

isPlayable

- (BOOL)isPlayable

Returns YES if the SoundView's sound data can be played without first being converted.

mouseDown:

- mouseDown:(NXEvent *)theEvent

Allows a selection to be defined by clicking and dragging the mouse.  This method takes control until a mouse-up occurs.  While dragging, the selected region is highlighted.  On mouse up, the delegate is sent the selectionChanged: message.  If isContinuous is YES, selectionChanged: messages are also sent while the mouse is being dragged.  You never invoke this method; it's invoked automatically in response to the user's actions. Returns self.

paste:

- paste:sender

Replaces the current selection with a copy of the sound data currently on the pasteboard.  If there is no selection the pasteboard data is inserted at the cursor position.  The pasteboard data must be compatible with the SoundView's data, as determined by the Sound method compatibleWith:.  If the paste is successful, the soundDidChange: message is sent to the delegate.  Returns self.

pasteboard:provideData:

- pasteboard:thePasteboard provideData:(const char *)pboardType

Places the SoundView's entire sound on the given pasteboard.  Currently, the pboardType argument must be ªNXSoundPboardTypeº, the pasteboard type that represents sound data.  Returns self.

pause:

- pause:sender

Pauses the current playback or recording session by invoking Sound's pause: method.  If no sound is being processed, returns nil; otherwise, returns self.

play:

- play:sender

Play the current selection by invoking Sound's play: method.  If there is no selection, the SoundView's entire Sound is played.  The willPlay: message is sent to the delegate before the selection is played; didPlay: is sent when the selection is done playing.  Returns self.

read:

- read:(void *)stream

Unarchives the SoundView by reading it from stream.  Returns self.

readSelectionFromPasteboard:

- readSelectionFromPasteboard:thePasteboard

Replaces the SoundView's current selection with the sound data on the given pasteboard.  The pasteboard data is converted to the format of the data in the SoundView (if possible).  If the SoundView has no selection, the pasteboard data is inserted at the cursor position.  Sets the current error code for the SoundView's Sound object (which you can retrieve by sending processingError to the Sound) and returns self.

record:

- record:sender

Replaces the SoundView's current selection with newly recorded material.  If there is no selection, the recording is inserted at the cursor.  The willRecord: message is sent to the delegate before the recording is started; didRecord: is sent after the recording has completed.  Recorded data is always taken from the CODEC microphone input.  Returns self.

reductionFactor

- (float)reductionFactor

Returns the SoundView's reduction factor, computed as

reductionFactor = sampleCount / displayUnits

resignFirstResponder

- resignFirstResponder

Resigns the position of first responder.  Returns self.

resume:

- resume:sender

Resumes the current playback or recording session by invoking Sound's resume: method.  If no sound is being processed, returns nil; otherwise, returns self.

scaleToFit

- scaleToFit

Recomputes the SoundView's reduction factor to fit the sound data (horizontally) within the current frame.  Invoked automatically when the SoundView's data changes and the SoundView is in autoscale mode.  If the SoundView isn't in autoscale mode, sizeToFit is invoked when the data changes.  You never invoke this method directly; a subclass can reimplement this method to provide specialized behavior.  Returns self.

selectAll:

- selectAll:sender

Creates a selection over the SoundView's entire Sound.  Returns self.

setAutoscale:

- setAutoscale:(BOOL)aFlag

Sets the SoundView's automatic scaling mode, used to determine how the SoundView is redisplayed when its data changes.  With autoscaling enabled (aFlag is YES), the SoundView's reduction factor is recomputed so the sound data fits within the view frame.  If it's disabled (aFlag is NO), the frame is resized and the reduction factor is unchanged.  If the SoundView is in a ScrollingView, autoScaling should be disabled (autoscaling is disabled by default).  Returns self.

setBackgroundGray:

- setBackgroundGray:(float)aGray

Sets the SoundView's background gray value to aGray; the default is NX_WHITE.  Returns self.

setBezeled:

- setBezeled:(BOOL)aFlag

If aFlag is YES, the display is given a bezeled border.  By default, the border of a SoundView display isn't bezeled.  If autodisplaying is enabled, the Sound is automatically redisplayed.  Returns self.

setContinuous:

- setContinuous:(BOOL)aFlag

Sets the state of continuous action messages.  If aFlag is YES, selectionChanged: messages are sent to the delegate as the mouse is being dragged.  If NO, the message is sent only on mouse up.  The default is NO.  Returns self.

setDelegate:

- setDelegate:anObject

Sets the SoundView's delegate to anObject.  The delegate is sent messages when the user changes or acts on the selection.  Returns self.

setDisplayMode:

- setDisplayMode:(int)aMode

Sets the SoundView's display mode, either NX_SOUNDVIEW_WAVE or NX_SOUNDVIEW_MINMAX (the default).  If autodisplaying is enabled, the Sound is automatically redisplayed.  Returns self.

setEditable:

- setEditable:(BOOL)aFlag

Enables or disables editing in the SoundView as aFlag is YES or NO.  By default, a SoundView is editable.  Returns self.

setEnabled:

- setEnabled:(BOOL)aFlag

Enables or disables the SoundView as aFlag is YES or NO.  The mouse has no effect in a disabled SoundView.  By default, a SoundView is enabled.  Returns self.

setForegroundGray:

- setForegroundGray:(float)aGray

Sets the SoundView's foreground gray value to aGray.  The default is NX_BLACK.  Returns self.

setOptimizedForSpeed:

- setOptimizedForSpeed:(BOOL)flag

Sets the SoundView to optimize its display mechanism.  Optimization greatly increases the speed with which data can be drawn, particularly for large sounds. It does so at the loss of some precision in representing the sound data; however, these inaccuracies are corrected as you zoom in on the data.  All SoundView's are optimized by default.  Returns self. 

setReductionFactor:

- setReductionFactor:(float)reductionFactor

Recomputes the size of the SoundView's frame, if autoscaling is disabled.  The frame's size (in display units) is set according to the formula

displayUnits = sampleCount / reductionFactor

Increasing the reduction factor zooms out, decreasing zooms in on the data.  If autodisplaying is enabled, the Sound is automatically redisplayed.  

If the SoundView is in autoscaling mode, or reductionFactor is less than 1.0, the method avoids computing the frame size and returns nil.  (In autoscaling mode, the reduction factor is automatically recomputed when the sound data changesÐsee scaleToFit:.)  Otherwise, the method returns self.  If reductionFactor is the same as the current reduction factor, the method returns immediately without recomputing the frame size.

setSelection:size:

- setSelection:(int)firstSample size:(int)sampleCount

Sets the selection to be sampleCount samples wide, starting with sample firstSample (samples are counted from 0).  Returns self.

setSound:

- setSound:aSound

Sets the SoundView's Sound object to aSound.  If autoscaling is enabled, the drawing coordinate system is adjusted so aSound's data fits within the current frame.  Otherwise, the frame is resized to accommodate the length of the data.  If autodisplaying is enabled, the SoundView is automatically redisplayed.  Returns self.

showCursor

- showCursor

Displays the SoundView's cursor.  This is usually handled automatically.  Returns self.

sizeTo::

- sizeTo:(NXCoord)width :(NXCoord)height

Sets the width and height of the SoundView's frame.  If autodisplaying is enabled, the SoundView is automatically redisplayed.  Returns self.

sizeToFit

- sizeToFit

Resizes the SoundView's frame (horizontally) to maintain a constant reduction factor.  This method is invoked automatically when the SoundView's data changes and the SoundView isn't in autoscale mode.  If the SoundView is in autoscale mode, scaleToFit is invoked when the data changes.  You never invoke this method directly; a subclass can reimplement this method to provide specialized behavior.  Returns self.

sound

- sound

Returns a pointer to the SoundView's Sound object.

soundBeingProcessed

- soundBeingProcessed

Returns the Sound object that's currently being played or recorded into.  Note that the actual Sound object that's being performed isn't necessarily the SoundView's sound (the object returned by the sound method); for efficiency, SoundView creates a private performance Sound object.  While this is generally an implementation detail, this method is supplied in case the SoundView's delegate needs to know exactly which object will be (or was) performed.

stop:

- stop:sender

Stops the SoundView's current recording or playback.  Returns self.

tellDelegate:

- tellDelegate:(SEL)theMessage

Sends theMessage to the SoundView's delegate with the SoundView as the argument.  If the delegate doesn't respond to the message, then it isn't sent.  You normally never invoke this method; it's invoked automatically when an action, such as playing or editing, is performed.  However, you can invoke it in the design of a SoundView subclass.  Returns self.

validRequestorForSendType:andReturnType:

- validRequestorForSendType:(NXAtom)sendType
andReturnType:(NXAtom)returnType

You never invoke this method; it's implemented to support services that act on sound data.

willPlay:

- willPlay:sender

Used to redirect delegate messages from the SoundView's Sound object; you never invoke this method directly.

willRecord:

- willRecord:sender

Used to redirect delegate messages from the SoundView's Sound object; you never invoke this method directly.

write:

- write:(void *)stream

Archives the SoundView by writing it to stream.  Returns self.

writeSelectionToPasteboard:types:

- writeSelectionToPasteboard:thePasteboard types:(NXAtom *)pboardTypes 

Places a copy of the SoundView's current selection on the given pasteboard.  The pboardTypes argument is currently ignored.  Returns self. 

Methods Implemented by the Delegate

didPlay:

- didPlay:sender

Sent to the delegate just after the SoundView's sound is played.

didRecord:

- didRecord:sender

Sent to the delegate just after the SoundView's sound is recorded into.

hadError:

- hadError:sender

Sent to the delegate if an error is encountered during recording or playback of the SoundView's sound.

selectionChanged:

- selectionChanged:sender

Sent to the delegate when the SoundView's selection changes.

soundDidChange:

- soundDidChange:sender

Sent to the delegate when the SoundView's sound data is edited.

willFree:

- willFree:sender

Sent to the delegate when the SoundView is freed.

willPlay:

- willPlay:sender

Sent to the delegate just before the SoundView's sound is played.

willRecord:

- willRecord:sender

Sent to the delegate just before the SoundView's sound is recorded into.